Skip to content

docs: Expand README for apds9960 driver.#222

Merged
nedseb merged 2 commits intomainfrom
apds9960-expend-readme
Mar 23, 2026
Merged

docs: Expand README for apds9960 driver.#222
nedseb merged 2 commits intomainfrom
apds9960-expend-readme

Conversation

@Charly-sketch
Copy link
Copy Markdown
Contributor

Closes #189
Parent issue #194


Description

Expand the apds9960 README to match the structure and level of detail of other drivers (e.g. ism330dl, wsen-hids).

Changes

  • Add Features section (ALS, RGB, proximity, gesture)
  • Document I2C address
  • Add Basic Usage example
  • Add complete API section covering all public methods
  • Structure API by feature (light, proximity, gesture)
  • Add usage-oriented code snippets for common operations
  • List existing examples in a table

Notes

  • Keep existing source attribution
  • Align wording and structure with other driver READMEs

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Expands the lib/apds9960 driver README to provide feature coverage, basic usage, and an API reference comparable to other drivers in this repository.

Changes:

  • Add new README sections for Features, I2C address, Basic Usage, API grouped by feature, configuration snippets, exceptions, and examples.
  • Update the mpremote example invocation to use the repo’s lib/<driver> mounting style.
  • Add notes about usage patterns (lazy activation, gesture polling) and available driver classes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread lib/apds9960/README.md Outdated
Comment on lines +36 to +37
Parfait — voici une version **alignée sur le style ism330dl / wsen-hids**, avec wording homogène, phrases courtes et impératives, et structure cohérente.

Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the French editorial sentence ("Parfait — …") from the README. It reads like an internal drafting note and breaks the otherwise user-facing English documentation style.

Suggested change
Parfait — voici une version **alignée sur le style ism330dl / wsen-hids**, avec wording homogène, phrases courtes et impératives, et structure cohérente.

Copilot uses AI. Check for mistakes.
Comment thread lib/apds9960/README.md Outdated
Comment on lines +62 to +63
## API

Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are two "## API" headings back-to-back (one at the start of the API section and another before "Ambient Light & Color"). This duplicates the top-level section and makes the outline confusing; keep a single "## API" header and nest the feature sections under it.

Suggested change
## API

Copilot uses AI. Check for mistakes.
Comment thread lib/apds9960/README.md Outdated
Comment on lines +150 to +153

* `get_prox_int_high_thresh()` / `set_prox_int_high_thresh(value)`
Get or set high proximity threshold

Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API list under Proximity documents get_prox_int_low_thresh() / get_prox_int_high_thresh(), but the driver also exposes get_proximity_int_low_threshold() / set_proximity_int_low_threshold() and get_proximity_int_high_threshold() / set_proximity_int_high_threshold() as public methods. Since this README claims a complete public API, these should be documented as well (or the README should clarify which set is preferred).

Suggested change
* `get_prox_int_high_thresh()` / `set_prox_int_high_thresh(value)`
Get or set high proximity threshold
* `get_proximity_int_low_threshold()` / `set_proximity_int_low_threshold(value)`
Get or set low proximity threshold (alternative method names)
* `get_prox_int_high_thresh()` / `set_prox_int_high_thresh(value)`
Get or set high proximity threshold
* `get_proximity_int_high_threshold()` / `set_proximity_int_high_threshold(value)`
Get or set high proximity threshold (alternative method names)

Copilot uses AI. Check for mistakes.
Comment thread lib/apds9960/README.md Outdated
Comment on lines +284 to +285
* The driver automatically enables sensors when needed (lazy activation).
* Gesture detection requires continuous polling via `gesture()`.
Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note about "automatically enables sensors when needed (lazy activation)" is a bit inaccurate/ambiguous: light/proximity reads do lazy-enable internally, but gesture() does not (it returns APDS9960_DIR_NONE unless gesture mode is enabled). Please tighten this wording to avoid suggesting that gesture is also auto-enabled.

Suggested change
* The driver automatically enables sensors when needed (lazy activation).
* Gesture detection requires continuous polling via `gesture()`.
* Ambient light and proximity reads automatically enable their respective sensors when needed (lazy activation).
* Gesture detection is not auto-enabled; enable gesture mode first (via the corresponding enable method) before continuously polling via `gesture()`.

Copilot uses AI. Check for mistakes.
Comment thread lib/apds9960/README.md Outdated
Comment on lines +265 to +266
* `APDS9960InvalidDevId` — invalid device ID detected
* `APDS9960InvalidMode` — invalid mode selection
Copy link

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a couple of trailing spaces in this section (e.g., after "selection"), which can cause unintended Markdown line breaks in some renderers. Please trim trailing whitespace.

Copilot uses AI. Check for mistakes.
@nedseb nedseb removed their assignment Mar 23, 2026
@nedseb
Copy link
Copy Markdown
Contributor

nedseb commented Mar 23, 2026

README réécrit en f225ec4 pour traiter tous les commentaires :

Corrections :

  1. Phrase ChatGPT en français — "Parfait — voici une version..." supprimée
  2. Double heading ## API — Fusionné en une seule section "## API Reference" avec sous-sections
  3. I²C Address — Intégrée dans le tableau "Supported Sensor" avec Device ID
  4. Basic UsageI2C(0, scl=Pin(22), sda=Pin(21))I2C(1) (STeaMi)
  5. Section "Supported Sensor" — Ajoutée avec specs
  6. Table exemples — Noms de fichiers sans préfixe examples/
  7. Newline finale — Ajoutée
  8. Toutes les méthodes préfixées sensor. — Cohérent avec les autres README

Copilot :

  1. Méthodes threshold alternativesget_proximity_int_low_threshold() / set_proximity_int_low_threshold() et high threshold documentées
  2. Lazy activation — Précisé : ALS et proximity sont auto-activés, gesture doit être activé manuellement
  3. Trailing whitespace — Supprimé

Prête à merger.

@nedseb nedseb merged commit 23c7f82 into main Mar 23, 2026
3 checks passed
@nedseb nedseb deleted the apds9960-expend-readme branch March 23, 2026 16:12
@semantic-release-updater
Copy link
Copy Markdown

🎉 This PR is included in version 0.0.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: Expand README for apds9960 driver.

3 participants